//+------------------------------------------------------------------+
//|                        File.mqh 文件操作基类头文件               |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
#include <Object.h>  // 引入CObject基类

//+------------------------------------------------------------------+
//| CFile类                                                          |
//| 功能：文件操作基类，封装通用文件I/O接口                          |
//| 继承：public CObject                                             |
//+------------------------------------------------------------------+
class CFile : public CObject
  {
protected:
   int               m_handle;             // 文件句柄（INVALID_HANDLE表示未打开）
   string            m_name;               // 已打开文件的名称/路径
   int               m_flags;              // 文件打开标志（组合FILE_*常量）

public:
   /**
    * @brief 构造函数
    * @details 初始化文件操作实例，设置默认状态
    */
                     CFile(void);

   /**
    * @brief 析构函数
    * @details 自动关闭已打开的文件，释放资源
    */
                    ~CFile(void);

   //--- 受保护成员访问接口
   /**
    * @brief 获取文件句柄
    * @return int - 文件句柄，未打开时返回INVALID_HANDLE
    */
   int               Handle(void)              const;

   /**
    * @brief 获取已打开文件的名称
    * @return string - 文件名称/路径，未打开时返回空字符串
    */
   string            FileName(void)            const;

   /**
    * @brief 获取文件打开标志
    * @return int - 标志组合（FILE_*常量）
    */
   int               Flags(void)               const;

   /**
    * @brief 设置文件编码格式
    * @param unicode [in] true表示Unicode编码，false表示ANSI编码
    * @note 仅在文件未打开时生效
    */
   void              SetUnicode(const bool unicode);

   /**
    * @brief 设置文件存储路径类型
    * @param common [in] true表示公共文件夹，false表示私有文件夹
    * @note 仅在文件未打开时生效
    */
   void              SetCommon(const bool common);

   //--- 核心文件操作接口
   /**
    * @brief 打开文件
    * @param file_name [in] 文件名称/路径
    * @param open_flags [in] 打开模式标志（FILE_READ/FILE_WRITE等）
    * @param delimiter [in] CSV模式下的分隔符（默认制表符）
    * @return int - 成功返回文件句柄，失败返回INVALID_HANDLE
    * @note 若已打开文件，会先自动关闭
    */
   int               Open(const string file_name,int open_flags,const short delimiter='\t');

   /**
    * @brief 关闭当前打开的文件
    * @note 释放资源并重置内部状态
    */
   void              Close(void);

   /**
    * @brief 删除当前打开的文件
    * @note 先关闭文件再执行删除操作
    */
   void              Delete(void);

   /**
    * @brief 获取文件大小（字节数）
    * @return ulong - 文件大小，未打开时返回0
    */
   ulong             Size(void);

   /**
    * @brief 获取当前文件指针位置
    * @return ulong - 指针位置（字节偏移量），未打开时返回0
    */
   ulong             Tell(void);

   /**
    * @brief 移动文件指针
    * @param offset [in] 偏移量
    * @param origin [in] 偏移基准（FILE_BEGIN/FILE_CURRENT/FILE_END）
    */
   void              Seek(const long offset,const ENUM_FILE_POSITION origin);

   /**
    * @brief 刷新文件缓冲区
    * @note 将内存数据强制写入磁盘
    */
   void              Flush(void);

   /**
    * @brief 判断是否到达文件末尾
    * @return bool - 到达末尾返回true，否则返回false
    */
   bool              IsEnding(void);

   /**
    * @brief 判断是否到达行末尾（仅文本模式有效）
    * @return bool - 到达行末尾返回true，否则返回false
    */
   bool              IsLineEnding(void);

   //--- 静态文件操作接口
   /**
    * @brief 删除指定文件
    * @param file_name [in] 要删除的文件名称
    * @param common_flag [in] 路径标志（FILE_COMMON表示公共文件夹）
    */
   void              Delete(const string file_name,const int common_flag=0);

   /**
    * @brief 检查文件是否存在
    * @param file_name [in] 要检查的文件名称
    * @param common_flag [in] 路径标志
    * @return bool - 存在返回true，否则返回false
    */
   bool              IsExist(const string file_name,const int common_flag=0);

   /**
    * @brief 复制文件
    * @param src_name [in] 源文件名称
    * @param common_flag [in] 源文件路径标志
    * @param dst_name [in] 目标文件名称
    * @param mode_flags [in] 复制模式（COPY_OVERWRITE/COPY_SKIP）
    * @return bool - 成功返回true，失败返回false
    */
   bool              Copy(const string src_name,const int common_flag,const string dst_name,const int mode_flags);

   /**
    * @brief 移动/重命名文件
    * @param src_name [in] 源文件名称
    * @param common_flag [in] 源文件路径标志
    * @param dst_name [in] 目标文件名称
    * @param mode_flags [in] 移动模式（MOVE_OVERWRITE/MOVE_SKIP）
    * @return bool - 成功返回true，失败返回false
    */
   bool              Move(const string src_name,const int common_flag,const string dst_name,const int mode_flags);

   //--- 文件夹操作接口
   /**
    * @brief 创建文件夹
    * @param folder_name [in] 文件夹名称
    * @return bool - 成功返回true，失败返回false
    */
   bool              FolderCreate(const string folder_name);

   /**
    * @brief 删除文件夹
    * @param folder_name [in] 文件夹名称
    * @return bool - 成功返回true，失败返回false
    */
   bool              FolderDelete(const string folder_name);

   /**
    * @brief 清空文件夹内容
    * @param folder_name [in] 文件夹名称
    * @return bool - 成功返回true，失败返回false
    */
   bool              FolderClean(const string folder_name);

   //--- 文件搜索接口
   /**
    * @brief 开始文件搜索
    * @param file_filter [in] 搜索过滤条件（支持通配符）
    * @param returned_filename [out] 第一个匹配的文件名
    * @return long - 搜索句柄，失败返回INVALID_HANDLE
    */
   long              FileFindFirst(const string file_filter,string &returned_filename);

   /**
    * @brief 获取下一个搜索结果
    * @param search_handle [in] 搜索句柄
    * @param returned_filename [out] 下一个匹配的文件名
    * @return bool - 找到返回true，结束返回false
    */
   bool              FileFindNext(const long search_handle,string &returned_filename);

   /**
    * @brief 结束文件搜索
    * @param search_handle [in] 搜索句柄
    */
   void              FileFindClose(const long search_handle);
  };
//+------------------------------------------------------------------+
